TSerial2 component

Properties	Methods	Data Types	Events

Copyright	Registration	Support	Source Code

Description

The TSerial2 component provides a way of accessing PC serial ports from a Delphi 2 32 bit application without having to directly use the Win32 API functions.

If you are using Delphi 1 then you need the basic Tserial component. This is available separately.

The TSerial2 component is a non-visual component like TTimer : it appears at design time as an icon, but is invisible at run-time.

You need to add one TSerial2 component to a form for each serial port that you need to access concurrently. If you need to access more than one port, but one at a time, you can change ports just by altering the Port property.

A comms port is opened by setting the component's Active property to True, and closed by setting the Active property to False. The Active property is not visible at design-time.

All the port configuration properties can be changed at run-time when a port is active : the TSerial2 component opens, closes and re-initialises the port(s) as necessary.


TSerial2 Properties

Active	MessageEndChar	RxQueueSize

Baudrate	MessageStartChar	RxWaiting

CheckParity	Name	StopBits

ComponentIndex	NotifyErrors	Tag

DataBits	Owner	TxQueueSize

ErrorCode	Parity	TxWaiting

FlowMode	Port

MessageAppendCount	RxEventMode


TSerial2 Methods

Break	SetSignal	ZapRxQueue

ReadChar	WriteChar	ZapTxQueue

ReadString	WriteString


TSerial2 Events

OnBreak	OnRing	OnTxEmpty

OnError	OnRxData	OnWriteCompleted

OnMessage	OnSignalChange


TSerial2 Data Types

eDataBits	eOpModes

eFlowControl	eParity

eModemInSignal	eStopBits

eModemOutSignal	sPorts

eNotifyErr


Active Property

Applies to

TSerial component

Declaration

property Active: Boolean;

Description

Note : Run-time only.

The Active property is the main "on/off" control for the TSerial2 component. It can only be set at run-time.

Typically, all the port properties such as Baudrate and Parity will be set before setting Active to True, although these can also be changed "on the fly" at run time.

Note that if an error (hardware not available for instance) prevents the port being opened, the Active property will not become True. Thus the success of opening the port can be gauged by setting and then testing Active :

Serial1.Baudrate := 4800;

Serial1.Active := True;

If Serial1.Active Then

     { Port open OK actions }

Else

     { Port open failed actions }


Baudrate Property

Applies to

TSerial component

Declaration

property Baudrate: Word;

Description

The Baudrate property sets the port Baudrate. The Baudrate must be one of the following values :

300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600,115200


CheckParity Property

Applies to

TSerial component

Declaration

property CheckParity: Boolean;

Description

The CheckParity property determines whether parity errors are detected on reception. If errors are detected, and CheckParity is set to True, then the erroneous characters are replaced with a '?'.


ComponentIndex Property

Applies to

TSerial component

Declaration

property ComponentIndex: Integer;

Description

Run-time and read only. The ComponentIndex property indicates the position of

the component in its owner's Components property list. The first component in

the list has a ComponentIndex value of 0, the second has a value of 1, and so

on.


DataBits Property

Applies to

TSerial component

Declaration

property DataBits:  eDataBits;

Description

Sets the number of databits per character for transmission and reception.

Value	Meaning

d7bit	7 data bits

d8bit	8 data bits


ErrorCode Property

Applies to

TSerial component

Declaration

property ErrorCode: Integer;

Description

Contains the last error code obtained from the serial port. The error code values can be looked up in the Win32 API documentation.


FlowMode Property

Applies to

TSerial component

Declaration

property FlowMode: eFlowControl;

Description

Selects the flow-control mode for the comms port. The following are valid flow modes:

Value	Meaning

fcNone	Use no flow control

fcRTS_CTS	Use RTS/CTS flow control.

When CTS is inactive, data transmission is suppressed.

When data cannot be accepted, RTS is set inactive.

fcDTR_DSR	Use DTR/DSR flow control

When DTR is inactive, data transmission is suppressed.

When data cannot be accepted, DSR is set inactive.

fcXON_XOF	Use XON/XOF flow control.

For both sending and receiving, an XOF character signals that no more data is to be sent until an XON character is received.


MessageStartChar Property

Applies to

TSerial component

Declaration

property MessageStartChar: Char;

Description

When operating in message mode (RxEventMode=rxMessage) this is the start character that identifies the beginning of a message. It defaults to STX (ASCII 2).


MessageEndChar Property

Applies to

TSerial component

Declaration

property MessageEndChar: Char;

Description

When operating in message mode (RxEventMode=rxMessage) this is the end character that identifies the end of a message. It defaults to ETX (ASCII 3).


MessageAppendCount Property

Applies to

TSerial component

Declaration

property MessageEndCount: Word;

Description

When operating in message mode (RxEventMode=rxMessage) this is the count of characters to be received after the end character defined by MessageEndChar.

This allows message extensions such as checksums, that may occur after the message end character, to be captured.


Name Property

Applies to

TSerial component

Declaration

property Name: TComponentName;

Description

The Name property contains the name of the component as referenced by other

components. By default, Delphi assigns sequential names based on the type of the

component, such as 'Button1', 'Button2', and so on. You may change these to suit

your needs.

Note:	Change component names only at design time.


NotifyErrors Property

Applies to

TSerial component

Declaration

property NotifyErrors: eNotifyErr;

Description

Selects the action to be taken in the event of a comms error occurring.

Value	Meaning

neDialog	Displays an application-modal dialog box containing a text description of the error.

neEvent	Calls the component's OnError event. The user can supply suitable error-handling code as the event handler.

neNone	Takes no special action. The user should check the component's ErrorCode property regularly to check if any error has occurred.


Owner Property

Applies to

TSerial component

Declaration

property Owner: TComponent;

Description

Run-time and read only. The Owner property indicates which component owns the

component.

The form owns all components that are on it. In turn, the form is owned by the

application.

When one component is owned by another, the memory for the owned component

is freed when its owner's memory is freed. This means that when a form is

destroyed, all the components on the form are destroyed also. Finally, when the

memory for the application itself is freed, the memory for the form (and all its

owned components) is also freed.

Don't confuse ownership of a component with being the parent of a component. A

parent is a windowed control that contains a child window. The parent and the

owner of a windowed component can be different components.


Port Property

Applies to

TSerial component

Declaration

property Port: sPorts;

Description

Defines the comms port number which the component is currently accessing.

For example :

for COM1:	use port := 1

for COM2:	use port := 2

Note

The port number can be changed even when the component is active. The component will automatically close and re-open the ports as necessary.


Parity Property

Applies to

TSerial component

Declaration

property Parity: eParity;

Description

Sets the parity bit operation of the port. Note that receive parity checking can be turned off using the CheckParity property, independent of the parity being generated on transmit.

Value	Meaning

paNone	No parity.

paOdd	Odd parity.

paEven	Even parity.

paMark	Parity is stuck at "mark" condition.

paSpace	Parity is stuck at "space" condition.


RxEventMode Property

Applies to

TSerial component

Declaration

property RxEventMode: eOpModes;

Description

Selects the operation mode for processing received data.

Events are generated by the component in response to received data.

OnRxData events signify that a variable amount of data is waiting in the receive queue to be picked up by the user.

OnMessage events signify that a user-defined message has been received in its entirety. The message is passed as a parameter to the event handler.

The events are mutually exclusive : either OnRxData events or OnMessage events will occur but not both.

Value	Meaning

rxNormal	Generate OnRxData events

rxMessage	Generate OnMessage events


RxQueueSize Property

Applies to

TSerial component

Declaration

property RxQueueSize: Word;

Description

Defines the size of the receive queue. This is the maximum number of characters that can be waiting for processing having been received from the port.


RxWaiting Property

Applies to

TSerial component

Declaration

property RxWaiting: Word;

Description

Returns the actual number of characters waiting to be processed in the receive queue.

Run-time only and read-only.


StopBits Property

Applies to

TSerial component

Declaration

property StopBits: eStopBits;

Description

Defines the number of stop bits sent with each character.

Value	Meaning

st1bit	One stop bit

st2bit	Two stop bits


Tag Property

Applies to

TSerial component

Declaration

property Tag: Integer;

Description

The Tag property is available to store an integer value as part of a component.

While the Tag property has no meaning to Delphi, your application can use the

property to store a value for its special needs.


TxQueueSize Property

Applies to

TSerial component

Declaration

property TxQueueSize: Word;

Description

Defines the size of the transmit queue. This is the maximum number of characters that can be waiting to be sent, having been received from the user application.


TxWaiting Property

Applies to

TSerial component

Declaration

property TxWaiting: Word;

Description

Returns the actual number of characters waiting to be transmitted.

Run-time only and read-only.


eDataBits Type

Declaration

type eDataBits = (d7bit, d8bit ) ;

Description

Defines the available options for the TSerial2 DataBits property.


eFlowControl Type

Declaration

type eFlowControl = (fcNone, fcRTS_CTS, fcDTR_DSR, fcXON_XOF) ;

Description

Defines the available options for the TSerial2 FlowMode property.


eParity Type

Declaration

type eParity = ( paNone, PaOdd, paEven, paMark, paSpace ) ;

Description

Defines the available options for the TSerial2 Parity property.


eStopBits Type

Declaration

type eStopBits = (st1bit, st2bit ) ;

Description

Defines the available options for the TSerial2 StopBits property.


eNotifyErr Type

Declaration

type eNotifyErr = (neDialog, neEvent, neNone) ;

Description

Defines the available options for the TSerial2 NotifyErrors property.


eOpModes Type

Declaration

type eOpModes = (rxNormal, rxMessage) ;

Description

Defines the available options for the TSerial2 RxEventMode property.


sPorts Type

Declaration

type sPorts = 1..9 ;

Description

Defines the subrange of allowed values for the TSerial2 Port property.


TMessageEvent Type

Declaration

type TMessageEvent = procedure (Sender : TObject ; RxMessage : String) of Object;

Description

Defines the type for the event-handler procedure for the OnMessage event.

The RxMessage parameter contains the received message.


TSignalChangeEvent Type

Declaration

type TSignalChangeEvent = procedure (Sender : TObject ; Signal : eModemInSignal ; SignalState : Boolean) of Object;

Description

Defines the type for the event-handler procedure for the OnSignalChange event.

The Signal parameter is of type eModemInSignal and defines the signal that has changed state (CTS, DSR, or RLSD (DCD)).

The SignalState parameter gives the new state (True/False) of the signal.


TWriteCompleted Type
TWriteCompletedEvent Type

Declaration

type  TWriteCompletedEvent  = procedure of Object;

Description

Defines the type for the event-handler procedure for the OnWriteCompleted event.


eModemInSignal Type

Declaration

type eModemInSignal = (msCTS, msDSR, msRLSD) ;

Description

Defines the type of modem signal that has caused an OnSignalChange event.


eModemOutSignal Type

Declaration

type eModemOutSignal = (msRTS, msDTR) ;

Description

Defines the type of modem signal that is to be changed by a call to the SetSignal method.


OnError Event

Applies to

TSerial component

Declaration

property OnError : TNotifyEvent;

Description

The OnError event occurs when a serial-port error is detected, if the error-handling mode set by the NotifyErrors property is set to neEvent.

When handling this event the user's code should examine the ErrorCode property to determine the nature of the error.


OnRxData Event

Applies to

TSerial component

Declaration

property OnRxData : TNotifyEvent;

Description

The OnRxData event occurs when there is data in the receive queue to be handled, if the received data handling mode set by the RxEventMode property is set to rxNormal.

NOTE : Windows does not guarantee to send a message for every character received, especially at higher baud rates. Therefore, the best plan is to use the OnRxData handler to process all the data that is currently in the receive queue, using successive calls to ReadChar or ReadString until the queue is empty.

Example :

procedure TForm1.Serial1RxData(Sender: TObject);

var

   in_char : Char;

begin

   while Serial1.ReadChar(in_char) > 0 do

      { process in_char }

end;


OnTxEmpty Event

Applies to

TSerial component

Declaration

property OnTxEmpty : TNotifyEvent;

Description

The OnTxEmpty event occurs when the transmit queue becomes empty. The user event handler can use the event to add more data to the transmit queue using the WriteChar or WriteString methods.

Note that a OnTxEmpty event occurs when the TSerial2 component first becomes active and when the port number is changed.


OnMessage Event

Applies to

TSerial component

Declaration

property OnMessage : TMessageEvent;

Description

The OnMessage event occurs when a message is received, if the received data handling mode set by the RxEventMode property is set to rxMessage.

Message handling works as follows :

A message starts with a character defined by the MessageStartChar property.

A message ends with a character defined by the MessageEndChar property.

The number of characters defined by the MessageAppendCount property will be included after the end character.

The maximum length of a message is 255 bytes, since the message is stored as a String.

The RxMessage parameter of the user event handler is a String that contains the received message.

Example :

A message consists of STX (ASCII 2), 10 data characters, ETX(ASCII 3) and a one-byte checksum.

Set	MessageStartChar := Chr(2)

MessageEndChar := Chr(3)

MessageAppendCount := 1

RxEventMode := rxMessage

The OnMessage event will occur when the entire message has been received.


OnBreak Event

Applies to

TSerial component

Declaration

property OnBreak : TNotifyEvent;

Description

The OnBreak event is triggered when a break signal is detected at the receive input. The length of interruption to the received signal that constitues a break is defined by the Windows device driver.


OnRing Event

Applies to

TSerial component

Declaration

property OnRing : TNotifyEvent

Description

The OnRing event is triggered when an “RI” (Ring Indicator) active signal is detected on the port.


OnSignalChange
OnSignalChange Event

Applies to

TSerial component

Declaration

property OnSignalChange : TSignalChangeEvent;

Description

The OnSignalChange event is triggered when a change is detected in one of the CTS, DSR, or RLSD (DCD) input signals of the port.

The event handler procedure is passed two parameters that define the signal that has changed and its new state :

The Signal parameter is of type eModemInSignal and defines the signal that has changed state (CTS, DSR, or RLSD (DCD)).

The SignalState parameter is a Boolean which gives the new state (True/False) of the signal.


OnWriteCompleted
OnWriteCompleted Event

Applies to

TSerial component

Declaration

property OnWriteCompleted : TWriteCompletedEvent;

Description

The OnWriteCompleted event is triggered when a write to the port completed asynchronously. This signal could be used to change the state of the port (eg. transmit-receive turnaround), or to signal that more data can be sent.


ReadChar Method

Applies to

TSerial component

Declaration

function ReadChar (var c : Char) : Integer;

Description

Reads one character from the input queue, if available.

The character is returned via the c parameter.

The function returns the number of characters read, which will be either 0 or 1.


ReadString Method

Applies to

TSerial component

Declaration

function ReadString (var s : String) : Integer;

Description

Reads up to 255 characters from the input queue, as many as are available.

The character is returned via the s parameter.

The function returns the number of characters read, which will be between  0 and 255.


WriteChar Method

Applies to

TSerial component

Declaration

procedure WriteChar (c : Char);

Description

Writes the character parameter c to the output queue.


WriteString Method

Applies to

TSerial component

Declaration

procedure WriteString (s : String);

Description

Writes the string parameter s to the output queue.


ZapRxQueue Method

Applies to

TSerial component

Declaration

procedure ZapRxQueue;

Description

Deletes any data that is currently in the receive queue.


ZapTxQueue Method

Applies to

TSerial component

Declaration

procedure ZapTxQueue;

Description

Deletes any data that is currently in the transmit queue.


Break Method

Applies to

TSerial component

Declaration

procedure Break (time : Integer);

Description

The Break procedure sends a “break” signal to the port. The time that the break lasts for is set by the time parameter, which gives the length of break required in milliseconds.


SetSignal Method

Applies to

TSerial component

Declaration

procedure SetSignal (signal : eModemOutSignal; state : Boolean) ;

Description

The SetSignal method allows the user to manipulate the state of the port’s RTS or DSR signals.

The signal parameter of type eModemOutSignal establishes which signal is to be changed, and can have values of msRTS or msDTR.

The state parameter is Boolean and sets whether the signal will be made active or inactive.


Copyright Notice

This product and documentation is Copyright © R J Crowther, 1995 - 1997

Versions :

SERIAL2	2.20	18/3/97

HELP FILE	2.20	19/3/97


Registration

Registration brings you the source code for TSERIAL2 and removes the shareware dialog box at startup.

Contact the author at :

Mr R J Crowther

20, Howe Road

Haverhill

Suffolk

CB9 9NJ

England

PLEASE NOTE - I am moving in March 1997

New address :

Mr R J Crowther

20, Copsewood Drive

Hereford

HR1 1AX

England

Email :

Compuserve 	100255,660

Internet	100255.660@compuserve.com

Compuserve :

The product is on Compuserve's SWREG registration forum. This is by far the easiest method of registration for Compuserve users. The registration code is 12627.

Unless you ask for another delivery method, the registered version will be e-mailed to you within a few days.

E-mail to Internet addresses will be accompanied by a UUENCODEd ZIP file of the programs.

Registration costs £ 10 or $ 17

I much prefer UK currency for direct orders, as bank conversion costs are high. The easiest method for this amount is to send a £ 10 bank note (bill).


Support

Contact the author, preferably by email :

Email :	Compuserve 	100255,660

Internet	100255.660@compuserve.com

I cannot guarantee a specific response to unregistered shareware customers. Registered copies will obtain a quicker response !